/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package org.rolgps.libnstack.protocol;

import org.rolgps.libnstack.exception.DatabaseException;

/**
 *
 * @author xeph
 */
public interface KVDB {

    
    /**
     * Authenticates with the database server.
     * If the user doesn't exist then you should suscribe()
     *
     * @param usr
     * @param passwd
     * @throws org.rolgps.libnstack.exception.DatabaseException
     */
    public void auth(String usr, String passwd) throws DatabaseException;


    /**
     * Suscribes the user to the database. If the user already exists then
     * it throws a DatabaseException.
     *
     * @param usr
     * @param passwd
     * @throws org.rolgps.libnstack.exception.DatabaseException
     */
    public void suscribe(String usr, String passwd) throws DatabaseException;

    /**
     *
     * Sets the key to be queried. Note: you may add only
     * <b>one</b> key to the set.
     * @param key
     * @return KVDB New database representation, only with
     * those elements that match the criteria.
     */
    public KVDB key(String key);

    //filter es un and
    /**
     * Filter adds a filtering criteria to the database.
     * It returns a representation of the database,
     * which is no more than a data set.
     *
     * Filter is lazy, just as key is. It means it won't
     * be executed until <code>next()</code> or <code>delete()</code>
     * are called.
     *
     * @param criteria Criteria to be used.
     * @return KVDB New database representation, only with
     * those elements that match the criteria.
     */
    public KVDB filter(String criteria);

    //al ser lazy, key y filter NO ejecutan nada hasta que
    //se llama a next.

    /**
     * Retrieve the element from the server. This sends
     * a message to the database backend asking for the
     * next result.
     * <p>
     * It also moves the pointer to the next position.
     * </p>
     *
     * @return true if has more elements, false if empty.
     * @throws org.rolgps.libnstack.exception.DatabaseException
     */
    public boolean next() throws DatabaseException;

    //obtiene el dato actual.
    /**
     * Get holds the value of the current pair, and returns null
     * if KVDB is an empty set.
     *
     * @return a String with the information.
     * @throws org.rolgps.libnstack.exception.DatabaseException
     */
    public String get() throws DatabaseException;
    
    //borra todo lo seleccionado por el criterio
    /**
     * Deletes everything in the dataset.
     * @throws org.rolgps.libnstack.exception.DatabaseException
     */
    public void delete() throws DatabaseException;
    
    /**
     * Adds a pair to the database. If the pair already exists
     * then it won't be added.
     * @param key
     * @param value
     * @throws org.rolgps.libnstack.exception.DatabaseException
     */
    public void add(String key, String value) throws DatabaseException;

    /**
     * Updates the current dataset to this value. Deletes the rest of the
     * key-value pairs if applied to a dataset with more than one element.
     *
     * @param newValue
     * @throws org.rolgps.libnstack.exception.DatabaseException
     */
    public void update(String newValue) throws DatabaseException;

}
